home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / winlib1.zip / UPDATE.DOC < prev   
Text File  |  1991-01-13  |  7KB  |  232 lines
  1.   This file contains last minute changes to The C Window Library.
  2.  
  3.  
  4.  
  5.   MakeSound()
  6.   -----------
  7.  
  8.   The MakeSound() function sounds a tone for a duration of time.  Here is the 
  9.   prototype:
  10.  
  11.            void MakeSound(unsigned freq, unsigned millisec)
  12.  
  13.   where freq, is the frequency of the tone (in Hertz) and millisec is the 
  14.   number of milliseconds to sound the tone.
  15.  
  16.  
  17.   Example:
  18.   --------
  19.  
  20.   #include <window.h>
  21.  
  22.   main()
  23.   {
  24.     WindowInitializeSystem();
  25.     /* Produce a 440 Hertz tone for 3 seconds */
  26.     MakeSound(440,3000);
  27.   }
  28.  
  29.   There is no error return for this function.
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.   The window_error_func function pointer
  40.   --------------------------------------
  41.  
  42.   The window_error_func function pointer can point to an error function that
  43.   is performed whenever there is an error encountered in one of The C Window
  44.   Library functions.  If the global variable check_existence_flag is set to 1
  45.   and there is an error, The C Window Library will automatically call
  46.   window_error_func.  Here is the prototype:
  47.  
  48.        void (*window_error_func)(int errcode, char *sourcefile, int sourceline,
  49.                                  char *funcname)
  50.  
  51.   The errcode is one of the defined error codes included in The C Window
  52.   Library.  Refer to page 6 of the main documentation for more information of
  53.   the error codes and their definitions.  The second argument is the name of
  54.   the file where the error occurred.  Only users with the source code to The
  55.   C Window Library will have access to this file.  The third argument is the
  56.   offending line in the source file of where the error occurred.  The last
  57.   argument is the name of the function of where the error occurred.
  58.  
  59.   By default window_error_func points to a void null function (VOIDNULLFN),
  60.   therefore no error function is called.
  61.  
  62.       Here is an example of how to implement automatic error checking:
  63.  
  64.  
  65.   #include <window.h>
  66.   #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(red,white)
  67.   void custom_error_func(int, char *, int, char *);
  68.  
  69.   WPOINTER w, error_window;
  70.   void initialize_error();
  71.  
  72.   main()
  73.   {
  74.     WindowInitializeSystem();
  75.     WindowSaveInitial(0);
  76.     window_error_func = custom_error_func;  /* Assign error function */
  77.     initialize_error();
  78.     WindowOpen(w);               /* will be flagged for an error */
  79.   }
  80.  
  81.   void initialize_error()    /* Initialize error window and error handler */
  82.   {
  83.     error_window =
  84.           WindowInitialize(BORDER,1,1,60,5,WHITEONRED,WHITEONRED,SINGLEBOX);
  85.     WindowOpen(error_window);
  86.   }
  87.  
  88.  
  89.   void custom_error_func(int errcode, char *sourcefile, int sourceline,
  90.                          char *funcname)
  91.   {
  92.     int ch;
  93.     MakeSound(100,500);           /* Produce an error beep */
  94.     if (errcode == NO_HEAP_MEM)   /* Always check for the heap memory error
  95.                                      separately */
  96.     {
  97.       VideoWriteString("You have ran out of Heap Memory",1,1);
  98.       VideoWriteString(
  99.         "Press 'Q' to quit program, Any other key to Continue...",2,1);
  100.     }
  101.  
  102.     else                         /* Display error window */
  103.     {
  104.       WindowClear(error_window);
  105.       WindowDisplay(error_window,1,EXPLODE);
  106.       WindowPrintf(error_window,
  107.        "Error Code: %d\nSource File: %s\nSource Line %d\nError Occurred in %s",
  108.        errcode,sourcefile,sourceline,funcname);
  109.       WindowWriteString(error_window,
  110.         "Press 'Q' to quit program, Any other key to Continue...",5,1);
  111.     }
  112.  
  113.     ch = GET_KEY();
  114.     if (ch == 'Q' || ch == 'q')
  115.       exit(0);
  116.     else
  117.     if (errcode != NO_HEAP_MEM)
  118.       WindowHide(error_window,CONTRACT);
  119.   }
  120.  
  121.  
  122.   The above example initializes an error window and sets the window_error_func
  123.   function pointer to point to the function custom_error_func().  Whenever an
  124.   error occurs in The C Window Library, custom_error_func() will be called.
  125.  
  126.   Please note the check to see if the NO_HEAP_MEM error has occurred.  It is
  127.   important that you check for this error condition separately.  The reason for
  128.   this is that if there is not enough heap memory, you may inadvertently call a
  129.   function in your error handler that calls on malloc() or any of the other
  130.   memory allocation related functions.  This will either freeze your system,
  131.   or more peculiarly, cause your error handler to be called in an infinite
  132.   loop because of the repeated failing calls to malloc() or its related
  133.   functions.  In the latter case, you will run out of stack space.
  134.  
  135.   If you want to unassign the window_error_code function pointer, use the
  136.   following line in your code:
  137.  
  138.                     window_error_func = VOIDNULLFN;
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.   Include files
  149.   -------------
  150.  
  151.   KEYCODES.H is now automatically included when WINDOW.H is included.
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.   Input Options
  162.   -------------
  163.  
  164.   There is a new option that can be used with the WindowGet..() family of
  165.   functions:
  166.  
  167.   CHECKREGEXP_IGNORECASE - This option checks to see if the string entered
  168.   matches the regular expression, but does a case insensitive check when a
  169.   letter is encountered.  For example "ABC", "abc", "Abc", etc. will be accepted
  170.   if the regular expression is "3[A-Z]" and the CHECKREGEXP_IGNORECASE option
  171.   is selected.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.   Macros
  181.   ------
  182.  
  183.   The following macros have now been added:
  184.  
  185.  
  186.   GET_BGROUND_COLOR(c) - Returns the background color of the video attribute c.
  187.  
  188.   GET_FGROUND_COLOR(c) - Returns the foreground color of the video attribute c.
  189.  
  190.  
  191.   VWINDOW_COORD_IN_VIEWPORT(w,row,col) - Returns 1 if the virtual window
  192.                                          coordinates (row,col) are inside the
  193.                                          viewport w, 0 otherwise.  The virtual
  194.                                          window must have w as a viewport.
  195.  
  196.  
  197.   WINDOW_BORDER_COLOR(w) - Returns the border color of the window w.
  198.  
  199.  
  200.   WINDOW_COLUMN(w) - Returns the absolute column of the upper left hand corner
  201.                      of the window.
  202.  
  203.   WINDOW_HEIGHT(w) - Returns the height of the text area of the window w.
  204.  
  205.  
  206.   WINDOW_PAGENUM(w) - Returns the video page of where the window will be
  207.                       displayed.
  208.  
  209.   WINDOW_RANK(w) - Returns the rank of the window w.
  210.  
  211.  
  212.   WINDOW_ROW(w) - Returns the absolute row coordinate of the upper left hand
  213.                   corner of the window w.
  214.  
  215.  
  216.   WINDOW_TEXT_COLOR(w) - Returns the text color of the window w.
  217.  
  218.  
  219.   WINDOW_WIDTH(w) - Returns the width of the text area of the window w.
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.